<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>ActiveRecord::Locking::Pessimistic</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" href="../../../css/reset.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/main.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/github.css" type="text/css" media="screen" />
<script src="../../../js/jquery-1.3.2.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/jquery-effect.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/main.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/highlight.pack.js" type="text/javascript" charset="utf-8"></script>

</head>

<body>     
    <div class="banner">
        
            <span>Ruby on Rails v4.0.0</span><br />
        
        <h1>
            <span class="type">Module</span> 
            ActiveRecord::Locking::Pessimistic 
            
        </h1>
        <ul class="files">
            
            <li><a href="../../../files/activerecord/lib/active_record/locking/pessimistic_rb.html">activerecord/lib/active_record/locking/pessimistic.rb</a></li>
            
        </ul>
    </div>
    <div id="bodyContent">
        <div id="content">
  
    <div class="description">
      
<p><a href="Pessimistic.html">Locking::Pessimistic</a> provides support for
row-level locking using SELECT ... FOR UPDATE and other lock types.</p>

<p>Pass <code>lock: true</code> to <code>ActiveRecord::Base.find</code> to
obtain an exclusive lock on the selected rows:</p>

<pre># select * from accounts where id=1 for update
Account.find(1, lock: true)</pre>

<p>Pass <code>lock: 'some locking clause'</code> to give a database-specific
locking clause of your own such as ‘LOCK IN SHARE MODE’ or ‘FOR UPDATE
NOWAIT’. Example:</p>

<pre>Account.transaction do
  # select * from accounts where name = 'shugo' limit 1 for update
  shugo = Account.where(&quot;name = 'shugo'&quot;).lock(true).first
  yuko = Account.where(&quot;name = 'yuko'&quot;).lock(true).first
  shugo.balance -= 100
  shugo.save!
  yuko.balance += 100
  yuko.save!
end</pre>

<p>You can also use <code>ActiveRecord::Base#lock!</code> method to lock one
record by id. This may be better if you don’t need to lock every row.
Example:</p>

<pre class="ruby"><span class="ruby-constant">Account</span>.<span class="ruby-identifier">transaction</span> <span class="ruby-keyword">do</span>
  <span class="ruby-comment"># select * from accounts where ...</span>
  <span class="ruby-identifier">accounts</span> = <span class="ruby-constant">Account</span>.<span class="ruby-identifier">where</span>(<span class="ruby-operator">...</span>)
  <span class="ruby-identifier">account1</span> = <span class="ruby-identifier">accounts</span>.<span class="ruby-identifier">detect</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">account</span><span class="ruby-operator">|</span> <span class="ruby-operator">...</span> }
  <span class="ruby-identifier">account2</span> = <span class="ruby-identifier">accounts</span>.<span class="ruby-identifier">detect</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">account</span><span class="ruby-operator">|</span> <span class="ruby-operator">...</span> }
  <span class="ruby-comment"># select * from accounts where id=? for update</span>
  <span class="ruby-identifier">account1</span>.<span class="ruby-identifier">lock!</span>
  <span class="ruby-identifier">account2</span>.<span class="ruby-identifier">lock!</span>
  <span class="ruby-identifier">account1</span>.<span class="ruby-identifier">balance</span> <span class="ruby-operator">-=</span> <span class="ruby-value">100</span>
  <span class="ruby-identifier">account1</span>.<span class="ruby-identifier">save!</span>
  <span class="ruby-identifier">account2</span>.<span class="ruby-identifier">balance</span> <span class="ruby-operator">+=</span> <span class="ruby-value">100</span>
  <span class="ruby-identifier">account2</span>.<span class="ruby-identifier">save!</span>
<span class="ruby-keyword">end</span>
</pre>

<p>You can start a transaction and acquire the lock in one go by calling
<code>with_lock</code> with a block. The block is called from within a
transaction, the object is already locked. Example:</p>

<pre>account = Account.first
account.with_lock do
  # This block is called within a transaction,
  # account is already locked.
  account.balance -= 100
  account.save!
end</pre>

<p>Database-specific information on row locking:</p>

<pre>MySQL: http://dev.mysql.com/doc/refman/5.1/en/innodb-locking-reads.html
PostgreSQL: http://www.postgresql.org/docs/current/interactive/sql-select.html#SQL-FOR-UPDATE-SHARE</pre>

    </div>
  


  


  
  


  


  
    <!-- Method ref -->
    <div class="sectiontitle">Methods</div>
    <dl class="methods">
      
        <dt>L</dt>
        <dd>
          <ul>
            
              
              <li>
                <a href="Pessimistic.html#method-i-lock-21">lock!</a>
              </li>
            
          </ul>
        </dd>
      
        <dt>W</dt>
        <dd>
          <ul>
            
              
              <li>
                <a href="Pessimistic.html#method-i-with_lock">with_lock</a>
              </li>
            
          </ul>
        </dd>
      
    </dl>
  

  



  

    

    

    


    


    <!-- Methods -->
        
      <div class="sectiontitle">Instance Public methods</div>
      
        <div class="method">
          <div class="title method-title" id="method-i-lock-21">
            
              <b>lock!</b>(lock = true)
            
            <a href="Pessimistic.html#method-i-lock-21" name="method-i-lock-21" class="permalink">Link</a>
          </div>
          
          
            <div class="description">
              <p>Obtain a row lock on this record. Reloads the record to obtain the
requested lock. Pass an SQL locking clause to append the end of the SELECT
statement or pass true for “FOR UPDATE” (the default, an exclusive row
lock). Returns the locked record.</p>
            </div>
          
          
          
          
          
            
            <div class="sourcecode">
              
              <p class="source-link">
                Source: 
                <a href="javascript:toggleSource('method-i-lock-21_source')" id="l_method-i-lock-21_source">show</a>
                
                  | <a href="https://github.com/rails/rails/blob/3d1bc89ec8e6558bac81c4e9fce82b586f742629/activerecord/lib/active_record/locking/pessimistic.rb#L61" target="_blank" class="github_url">on GitHub</a>
                
              </p>
              <div id="method-i-lock-21_source" class="dyn-source">
                <pre><span class="ruby-comment"># File activerecord/lib/active_record/locking/pessimistic.rb, line 61</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">lock!</span>(<span class="ruby-identifier">lock</span> = <span class="ruby-keyword">true</span>)
  <span class="ruby-identifier">reload</span>(<span class="ruby-value">:lock</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">lock</span>) <span class="ruby-keyword">if</span> <span class="ruby-identifier">persisted?</span>
  <span class="ruby-keyword">self</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
            
          </div>
        
        <div class="method">
          <div class="title method-title" id="method-i-with_lock">
            
              <b>with_lock</b>(lock = true)
            
            <a href="Pessimistic.html#method-i-with_lock" name="method-i-with_lock" class="permalink">Link</a>
          </div>
          
          
            <div class="description">
              <p>Wraps the passed block in a transaction, locking the object before
yielding. You pass can the SQL locking clause as argument (see
<code>lock!</code>).</p>
            </div>
          
          
          
          
          
            
            <div class="sourcecode">
              
              <p class="source-link">
                Source: 
                <a href="javascript:toggleSource('method-i-with_lock_source')" id="l_method-i-with_lock_source">show</a>
                
                  | <a href="https://github.com/rails/rails/blob/3d1bc89ec8e6558bac81c4e9fce82b586f742629/activerecord/lib/active_record/locking/pessimistic.rb#L69" target="_blank" class="github_url">on GitHub</a>
                
              </p>
              <div id="method-i-with_lock_source" class="dyn-source">
                <pre><span class="ruby-comment"># File activerecord/lib/active_record/locking/pessimistic.rb, line 69</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">with_lock</span>(<span class="ruby-identifier">lock</span> = <span class="ruby-keyword">true</span>)
  <span class="ruby-identifier">transaction</span> <span class="ruby-keyword">do</span>
    <span class="ruby-identifier">lock!</span>(<span class="ruby-identifier">lock</span>)
    <span class="ruby-keyword">yield</span>
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
            
          </div>
                    </div>

    </div>
  </body>
</html>    